fix(types): a link:/file: install's refusal states the LIMIT, not a false install remedy - #17030

Fixes #15045

Clause-②: no

The link: / file: sub-case #14278 deliberately left standing was refusing correctly and explaining itself wrongly. This PR changes only what the refusal SAYS. The refusal, its kind, its code, its exit path and the finder's accept set are byte-for-byte what they were.

⛔ Not built here: the card's other route — the second verification axis (realpath(node_modules/KEY) compared against the declared location) — which would make these installs LOAD. That relaxes a published accept set and is a contract decision, not a diagnostic one. The card stays open for it.

The failure, driven

A host app declaring {"dependencies": {"linked-other": "link:../elsewhere"}}, node_modules/linked-other a real symlink to a sibling directory whose manifest is named @fixture/some-other-name, ESM-only exports. hostRequire.resolve throws ERR_PACKAGE_PATH_NOT_EXPORTED (measured), so the #14041 fallback decides.

BEFORE — verbatim:

Cannot find module 'linked-other': the host app DECLARES it (dependencies: "link:../elsewhere") but it could not be resolved.
  host app: /tmp/os-link-mismatch-imXEMJ/app

  This is an INSTALL problem, not a declaration problem — the declaration is
  already there, so re-reading the package.json will not help. Check:
    • dependencies never installed, or installed before the declaration was added → run `pnpm install` in /tmp/os-link-mismatch-imXEMJ/app
    • a production prune / filtered deploy dropped it (devDependencies and
      optionalDependencies go first)
    • it IS installed but its "main"/"exports" points at a dist that was never built
  (resolver: No "exports" main defined in /tmp/os-link-mismatch-imXEMJ/app/node_modules/linked-other/package.json)

All three prescribed checks are measurably false for this shape. The finder had just read the manifest at node_modules/linked-other, so: the package is on disk (not "never installed"), it was not pruned, and its import target exists (the dist IS built). The operator runs pnpm install, nothing changes, and goes hunting for a build that is not broken.

AFTER — same input, same fixture:

Cannot load module 'linked-other': the host app DECLARES it (dependencies: "link:../elsewhere"), a package IS installed at that key, and this ESM fallback cannot confirm it is the declared one.
  host app: /tmp/os-link-mismatch-COkaxL/app
  installed at: /tmp/os-link-mismatch-COkaxL/app/node_modules/linked-other
  its package.json is named: "@fixture/some-other-name"
  this finder expected: "linked-other"

  This is NOT an install problem, and NOT a declaration problem — the package is
  on disk and the declaration is right, so re-running `pnpm install`, un-pruning a
  deploy and rebuilding a dist all change nothing here.
  What it IS: a "link:" / "file:" declaration names a LOCATION, not a package. The
  manifest at the other end may carry any name, and the specifier holds none for
  this finder to expect, so the KEY is all it has to check against. A git or
  tarball URL (github:owner/repo, https://.../pkg.tgz) names no on-disk location
  either and lands here the same way.
  The refusal is deliberate: this fallback stays strictly tighter than the
  CommonJS resolution it backs up, and will not load a directory it cannot tie to
  the declaration. Only a package publishing no `require` condition reaches it at
  all, so nothing that loads today is affected either way.
  What DOES change it — make the two names AGREE, from whichever end you own:
    • declare the linked package under its own name: key "@fixture/some-other-name",
      pointing at the same location, and import it under that name
    • or set the linked package's own "name" to "linked-other", if that
      directory is yours to edit
  Either way the key becomes the expectation this finder checks, and the load
  succeeds through this same fallback.
  (resolver: No "exports" main defined in ...)

Every claim in the new message was measured, not reasoned. Both closing remedies were driven and both LOAD (pinned as tests): renaming the key to the linked manifest's name, and renaming the linked manifest to the key.

⛔ One remedy was deliberately removed during drafting rather than printed: "have the package publish a require condition." It does make the load succeed — and that is the problem. A dual build resolves through CommonJS, so #13330's condition re-decision runs instead, packageRootOf fails to recognise the differently-named root for exactly the reason this finder does, and ?? resolved hands back the require build. The operator gets a load plus the second-instance split #13330 exists to close, silently. That is pinned as today's behaviour by the #15044 suite (BOUNDARY: a link: target whose manifest names something else keeps today's load), which this PR leaves untouched and green. A remedy the runtime honours while making things quietly worse is not one worth printing.

The refusal did NOT move

The predicate is on the declaration, never on the on-disk shape: an unrecognised specifier spelling falls out as "the key is a promise" and keeps today's wording — the conservative direction, matching how ALIAS_DECLARATION_PROTOCOLS already defaults.

Ablation — the pins can fail

Neutralising declarationNamesNoPackage to return false restores the pre-fix behaviour exactly.

• mutation proven on disk before running: injected marker grep -c = 1; blob hash e2c58a0d45… vs HEAD's f72b9ca85d… (different, so the edit landed)
• result: 5 failed | 76 passed — the four A link: / file: install whose manifest name differs from the key still keeps the wrong INSTALL wording — the location-carrying sub-case #14278 could not reach #15045 wording pins plus the re-worded An aliased install ("foo": "npm:bar@1") fails createHostImporter's manifest-name check, so an ESM-only aliased package keeps the wrong INSTALL wording #14278 BOUNDARY pin. Direction: turned red, as predicted.
• the tests that stayed GREEN under ablation are the coherent set: refusal-unchanged, negative control, both remedy pins and all three tightness controls — because neutralising the predicate restores a world in which those all still hold.
• restore leg proven by hash equality against the HEAD blob (f72b9ca85d…) and an empty git diff HEAD, not by an exit code. The script carried a trap … EXIT INT TERM with absolute paths throughout.

Subject resolution: node.test.ts imports ./node.js, a same-package relative specifier vitest resolves to src/node.ts, so the ablation exercises source directly — no dist/ leg is involved.

Changeset — MEASURED, not guessed

@objectstack/types publishes and this is operator-visible text, so skip-changeset was tested rather than assumed. Built, then npm pack --dry-run --json, then every one of the 16 packed paths searched:

The control fires, so the probe works; the needle is present, so this ships. Changeset written: @objectstack/types: patch.

Clause ② — re-derived from this diff

• Accept set: unchanged, per the table above and the ablation's green set.
• Published surface: not widened. Nothing new is exported; the new fallback outcome member lives on the module-local DeclaredCjsResolveFallback type and HostImportFailureKind still has exactly its three members. The only occurrence of a new identifier in the emitted .d.ts is a {@link unverifiableLocationMessage} inside the JSDoc of an already-exported type — read out at dist/node.d.ts:128, documentation prose, not a declaration. check:dts-closure and check:published-files both green.

Minting a fourth HostImportFailureKind for this sub-case was considered and rejected: it would widen a published union for a wording fix. The trade is recorded in the kind's own docblock, including its cost — a consumer that re-words this kind LOCALLY instead of deferring to err.message still prints its own install remedy here (the #14270 class). See acceptance notes.

Verification

All at final commit 8e79a6bb3a.

• pnpm --filter @objectstack/types test — 19 files, 584 tests passed
• pnpm --filter @objectstack/types typecheck — exit 0. It really does compile the test file: tsc --listFiles | grep -c src/node.test.ts = 1, so this is a measurement, not an assumption.
• pnpm --filter '@objectstack/types^...' build — exit 0 (needed: an unbuilt packages/spec dist reddens an unrelated pre-existing test in this suite; the first run reproduced exactly that and it is not from this diff)
• gate families derived with node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack, re-derived after a fetch (no new families), reconciled with --ran: 56 derived, 56 run, 0 UNRUN
• 53 of 56 exit 0. Three exit 3 = PREREQUISITE NOT MET, which those gates print as "NOT MEASURED — neither a pass nor a failure": check:dual-build-cjs-loads and check:type-check-debt need a whole-workspace build (CI's lint.yml builds the closure first). check:lean-entry-closure was the third — its prerequisite WAS met locally by building @objectstack/objectql, after which it is a real green: "2 published condition(s) measured from a real load."
• pnpm lint (eslint . --no-inline-config) — the full repo-scoped union, not a narrowing: 6394 files, 0 errors, 0 warnings, exit 0, re-run at 8e79a6bb3a.
• control characters: grep -naP over both touched source files returns nothing; pnpm check:nul-bytes green.

Docs drift — audited, no page edited

The bot listed 13 hand-written pages plus 1 release-owned (content/docs/releases/v17.mdx, read-only — audited, never edited from a code PR).

Same tree, verified per file. ⛔ The bot's own footer says its checkout carried uncommitted changes, so its sha is not a pin. Instead all 14 paths were compared blob-for-blob between this worktree and 16aeaf481c92: 14/14 identical, 0 differing, 0 missing. These are the pages the bot read.

Every row is a wrong row, and each was read out rather than counted. All 14 are anchored on string literals, not symbols — node_modules (a literal in declaredCjsResolveFallback) and package.json (literals in hostInstalledPackageDir and manifestNameAt). All 27 anchor occurrences across the 14 pages were printed and read. They are: scaffold directory trees (examples, your-first-project, plugins/development, plugins/index, kernel/plugin-spec, objectql/schema), the engines field (troubleshooting), oclif plugin config (plugins/index), the emitted manifest's dependencies (cli, upgrading, kernel/index), a wildcard-exclusion list (cli), a CHANGELOG read path (upgrading), the published spec schemas (skills-reference), and — on the release-owned page — @objectstack/cli's sealed exports map from #15325. None describes the host importer, its failure kinds, or its refusal text. A grep for host-importer terms across all 14 returns zero, with the same pattern firing 56 times in packages/types/src/node.ts as its control.

The one row that came close, and why it still stands. content/docs/deployment/tenancy-modes.mdx is the only page in all of content/ that quotes host-importer operator text. It reproduces formatOrganizationsAbsentFatal plus the undeclared arm of formatOrganizationsInstallRemedy ("declare it in the app's package.json and install"), and adds one sentence about the other arm: "If the package is already declared but the install is broken, the message says so and tells you to repair the install rather than re-read package.json." Not falsified, on two counts: this PR does not touch formatOrganizationsInstallRemedy, so the org path's rendered remedy is byte-identical; and that sentence is scoped to "the install is broken", which is precisely the antecedent this sub-case does not satisfy. It is now mildly incomplete rather than wrong — a third shape exists (declared, installed, not broken, still refused) that the page does not mention — and that incompleteness is the same consequence recorded in the acceptance notes below.

The sweep the bot structurally cannot run. Its disclosed input-vs-emitter blind spot means a page quoting the OLD refusal wording would name the words, not declaredCjsResolveFallback, and could never appear in its list. Swept content/ directly for the old message's distinctive strings:

Two further sweeps — link: / file: / alias-shaped prose, and host-importer / declaration-gate prose — return zero pages across all of content/.

Controls, so every zero above is a reading and not a silent miss. The sweep machinery reaches content/ (organization wall is INACTIVE → 1 hit, tenancy-modes.mdx:237). Both zero-returning patterns fire where their subject lives: 2 files each under packages/types/src/.

What this did and did not answer. It answers that no hand-written page states, quotes or paraphrases the wording this PR changes, and that no page describes what a failed link: / file: load tells an operator. It does not answer the bot's two disclosed blind spots in general — the 156 unreachable route-ledger rows, and input-stated rules on pages sharing no token with their emitter. The second one is the one that matters on a message diff, which is why it was swept by hand above rather than delegated. ⇒ No documentation page is falsified by this PR, so no page is edited and the declared file surface does not widen.

验收备注

• Un-driven observation, noted rather than filed. formatOrganizationsInstallRemedy (packages/cli/src/commands/serve.ts) mints its own remedy sentence for declared-unresolvable instead of deferring to err.message, and formatOrganizationsAbsentFatal prints that remedy above the cause: line. On the multi-org path this sub-case would therefore show the corrected cause text beside a stale "Repair the INSTALL" bullet. This is the documented Three failure-kind remedy formatters word the new declared-no-loadable-entry kind as "declare it in the app's package.json" — wrong for a declared, installed package #14270 class and is now named in the kind's docblock. ⚠️ Filed as an observation and not as a card because it was reasoned from source, not driven — reaching it needs the enterprise org runtime declared under a location specifier with a mismatched key, which is out of this card's declared file surface. Successor: whoever builds A link: / file: install whose manifest name differs from the key still keeps the wrong INSTALL wording — the location-carrying sub-case #14278 could not reach #15045's remaining half (the second verification axis) is in exactly this code path, since making these installs load removes the sub-case outright. The two seams in packages/cli that got it right (formatI18nLoadDiagnostic, and the declared-no-loadable-entry arm) interpolate the kind TOKEN only and are correct here already.
• Files touched, both inside the declared surface plus its test: packages/types/src/node.ts, packages/types/src/node.test.ts, and the changeset.
• The An aliased install ("foo": "npm:bar@1") fails createHostImporter's manifest-name check, so an ESM-only aliased package keeps the wrong INSTALL wording #14278 BOUNDARY pin was asserting /INSTALL problem/ — i.e. it pinned the wrong wording. It is kept, still asserting the refusal, and now asserts that wording is gone; the replacement wording is pinned in the new A link: / file: install whose manifest name differs from the key still keeps the wrong INSTALL wording — the location-carrying sub-case #14278 could not reach #15045 suite. The comment records that it changed and why.

Generated by Claude Code